chrome.userScripts

Opis

Użyj interfejsu userScripts API, aby wykonać skrypty użytkownika w kontekście skryptów użytkownika.

Uprawnienia

userScripts

Aby używać interfejsu User Scripts API, chrome.userScripts, dodaj do pliku manifest.json uprawnienia "userScripts" i "host_permissions" dla witryn, w których chcesz uruchamiać skrypty.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Dostępność

Chrome 120+ MV3+

Pojęcia i zastosowanie

Skrypt użytkownika to fragment kodu wstrzyknięty do strony internetowej w celu modyfikacji jej wyglądu lub działania. W przeciwieństwie do innych funkcji rozszerzenia, takich jak skrypty treści i interfejs API chrome.scripting, interfejs API skryptów użytkownika umożliwia uruchamianie dowolnego kodu. Ten interfejs API jest wymagany w przypadku rozszerzeń, które uruchamiają skrypty dostarczone przez użytkownika i których nie można przesłać w ramach pakietu rozszerzenia.

Włączanie interfejsu userScripts API

Gdy Twoje rozszerzenie otrzyma uprawnienia do korzystania z interfejsu userScripts API, użytkownicy muszą włączyć odpowiedni przełącznik, aby umożliwić mu korzystanie z interfejsu API. Wymagany przełącznik i działanie interfejsu API po wyłączeniu różnią się w zależności od wersji Chrome.

Aby określić, które przełączniki musi włączyć użytkownik, na przykład podczas rejestracji nowego użytkownika, wykonaj te czynności:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version > 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

W sekcjach poniżej opisujemy różne przełączniki i sposób ich włączania.

Wersje Chrome starsze niż 138 (przełącznik trybu programisty)

Jako twórca rozszerzenia masz już włączony tryb programisty w swojej instalacji Chrome. Użytkownicy muszą też włączyć tryb programisty.

Możesz skopiować i wklejać te instrukcje w dokumentacji rozszerzenia dla użytkowników.

  1. Otwórz stronę Rozszerzenia, wpisując chrome://extensions w nowej karcie. (adresy URL chrome:// nie można łączyć).

  2. Włącz tryb programisty, klikając przełącznik obok opcji Tryb programisty.

    Wyróżnione przełączniki trybu programisty na stronie rozszerzeń w Chrome

    Strona Rozszerzenia (chrome://extensions)

Chrome w wersji 138 lub nowszej (przełącznik Zezwalaj na skrypty użytkownika)

Przełącznik Zezwalaj na skrypty użytkownika znajduje się na stronie szczegółów każdego rozszerzenia (np. chrome://extensions/?id=TWÓJ_IDENTYFIKATOR_ROZSZERZENIA).

Możesz skopiować i wkleić te instrukcje do dokumentacji rozszerzenia dla użytkowników:

  1. Otwórz stronę Rozszerzenia, wpisując chrome://extensions w nowej karcie. (adresy URL chrome:// nie można łączyć).
  2. Aby wyświetlić szczegółowe informacje o rozszerzeniu, kliknij przycisk „Szczegóły” na karcie rozszerzenia.
  3. Kliknij przełącznik obok opcji Zezwalaj na skrypty użytkownika.
Przełącznik Zezwalaj na skrypty użytkownika na stronie z informacjami o rozszerzeniu
Zezwalaj na skrypty użytkownika (chrome://extensions/?id=abc...)

Sprawdzanie dostępności interfejsu API

Aby sprawdzić, czy interfejs userScripts API jest włączony, wykonaj podane niżej czynności. Działa on we wszystkich wersjach Chrome. Ta kontrola próbuje wywołać metodę chrome.userScripts(), która powinna zawsze zakończyć się sukcesem, gdy interfejs API jest dostępny. Jeśli wywołanie zwróci błąd, interfejs API jest niedostępny:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Praca w odizolowanych światach

Zarówno skrypty użytkownika, jak i skrypty treści mogą działać w świecie izolowanym, jak i w świecie głównym. Odseparowany świat to środowisko wykonania, które nie jest dostępne dla strony hosta ani innych rozszerzeń. Dzięki temu skrypt użytkownika może zmienić środowisko JavaScript bez wpływu na stronę hosta lub skrypty użytkownika i treści innych rozszerzeń. Z drugiej strony skrypty użytkownika (i skrypty treści) nie są widoczne dla strony hosta ani skryptów użytkownika i skryptów treści innych rozszerzeń. Scenariusze działające w świecie głównym są dostępne dla stron hosta i innych rozszerzeń oraz są widoczne dla stron hosta i innych rozszerzeń. Aby wybrać świat, prześlij wartość "USER_SCRIPT" lub "MAIN", gdy wywołujesz funkcję userScripts.register().

Aby skonfigurować zasady zabezpieczeń treści dla wszystkich użytkowników na świecie, USER_SCRIPT, wywołaj funkcję userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Wiadomości

Podobnie jak skrypty treści i dokumenty poza ekranem, skrypty użytkownika komunikują się z innymi częściami rozszerzenia za pomocą wiadomości (co oznacza, że mogą wywoływać runtime.sendMessage() i runtime.connect() tak samo jak każda inna część rozszerzenia). Są one jednak odbierane za pomocą specjalnych modułów obsługi zdarzeń (czyli nie używają onMessage ani onConnect). Te moduły obsługi mają nazwy runtime.onUserScriptMessage i runtime.onUserScriptConnect. Dedykowane procedury obsługi ułatwiają identyfikację komunikatów ze skryptów użytkownika, które są mniej zaufanym kontekstem.

Przed wysłaniem wiadomości musisz wywołać funkcję configureWorld(), ustawiając argument messaging na wartość true. Pamiętaj, że argumenty csp i messaging mogą być przekazywane jednocześnie.

chrome.userScripts.configureWorld({
  messaging: true
});

Aktualizacje rozszerzeń

Skrypty użytkownika są usuwane, gdy rozszerzenie jest aktualizowane. Możesz je dodać ponownie, uruchamiając kod w obiekcie runtime.onInstalled w obiekcie rozszerzenia service worker. Odpowiadaj tylko na "update"powód przekazany do wywołania zwrotnego zdarzenia.

Przykład

Ten przykład pochodzi z przykładowego skryptu userScript w naszym repozytorium przykładów.

Rejestrowanie skryptu

Poniższy przykład pokazuje podstawowy wywołanie funkcji register(). Pierwszy argument to tablica obiektów definiujących skrypty, które mają zostać zarejestrowane. Dostępnych jest więcej opcji niż pokazano tutaj.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Typy

ExecutionWorld

Środowisko JavaScript, w którym ma działać skrypt użytkownika.

Typ wyliczeniowy

„MAIN”
Określa środowisko wykonania DOM, czyli środowisko wykonania udostępnione kodom JavaScript strony hosta.

„USER_SCRIPT”
Określa środowisko wykonania, które jest specyficzne dla skryptów użytkownika i nie podlega zasadom CSP strony.

InjectionResult

Chrome w wersji 135 lub nowszej

Właściwości

  • documentId

    ciąg znaków

    Dokument powiązany z wstrzyknięciem.

  • błąd

    string opcjonalny

    Błąd (jeśli wystąpił). Funkcje error i result wykluczają się nawzajem.

  • frameId

    liczba

    Kadr powiązany z wstawieniem.

  • wynik

    dowolne opcjonalne

    Wynik wykonania skryptu.

InjectionTarget

Chrome 135 lub nowszy

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Określa, czy skrypt ma być wstrzykiwany do wszystkich klatek w karcie. Wartość domyślna to fałsz. Nie może być spełniony, jeśli podano parametr frameIds.

  • documentIds

    string[] opcjonalne

    Identyfikatory konkretnych dokumentów, do których mają zostać wstrzyknięte dane. Nie można go ustawić, jeśli jest ustawiona opcja frameIds.

  • frameIds

    number[] opcjonalny

    Identyfikatory konkretnych klatek, do których mają być wstrzyknięte.

  • tabId

    liczba

    Identyfikator karty, do której chcesz wstrzyknąć kod.

RegisteredUserScript

Właściwości

  • allFrames

    wartość logiczna opcjonalna

    Jeśli ma wartość prawda, zostanie wstrzyknięty do wszystkich ramek, nawet jeśli nie jest to najwyższa ramka na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresu URL. Jeśli wymagania te nie są spełnione, nie zostanie wstrzyknięta do ramek podrzędnych. Domyślnie ustawiona jest wartość false, co oznacza, że dopasowywany jest tylko górny element.

  • excludeGlobs

    string[] opcjonalne

    Określa wzorce symboli wieloznacznych dla stron, na które skrypt użytkownika NIE BĘDZIE wstrzykiwany.

  • excludeMatches

    string[] opcjonalne

    Wyklucza strony, na które skrypt użytkownika miałby zostać wstrzyknięty. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania.

  • id

    ciąg znaków

    Identyfikator skryptu użytkownika określonego w wywołaniu interfejsu API. Ta nazwa nie może się zaczynać od „_”, ponieważ jest zarezerwowana jako prefiks wygenerowanych identyfikatorów skryptu.

  • includeGlobs

    string[] opcjonalne

    Określa wzorce symboli wieloznacznych dla stron, na które zostanie wstrzyknięty skrypt użytkownika.

  • js

    ScriptSource[] opcjonalnie

    Lista obiektów ScriptSource definiujących źródła skryptów, które mają być wstrzykiwane na pasujące strony. Ta właściwość musi być określona w przypadku ${ref:register} i musi być niepustą tablicą.

  • pasuje do

    string[] opcjonalne

    Określa, na których stronach ma być wstrzykiwany skrypt użytkownika. Więcej informacji o składni tych ciągów znajdziesz w artykule Wzorce dopasowania. Ta właściwość musi być określona w przypadku ${ref:register}.

  • runAt

    RunAt opcjonalny

    Określa, kiedy pliki JavaScript są wstrzykiwane na stronę internetową. Preferowaną i domyślną wartością jest document_idle.

  • świat

    ExecutionWorld opcjonalny

    Środowisko wykonawcze JavaScript, w którym ma być uruchamiany skrypt. Wartość domyślna to `USER_SCRIPT`.

  • worldId

    string opcjonalny

    Chrome 133 lub nowszy

    Określa identyfikator świata skryptu użytkownika, w którym ma być wykonywany. Jeśli go pominiesz, skrypt zostanie wykonany w domyślnym świecie skryptu użytkownika. Obowiązuje tylko wtedy, gdy world jest pominięty lub ma wartość USER_SCRIPT. Wartości z początkowym podkreśleniem (_) są zarezerwowane.

ScriptSource

Właściwości

  • kod

    string opcjonalny

    Ciąg tekstowy zawierający kod JavaScript do wstrzyknięcia. Musisz podać dokładnie jedną z tych właściwości: file lub code.

  • plik

    string opcjonalny

    Ścieżka do pliku JavaScript, który ma zostać wstrzyknięty względem katalogu głównego rozszerzenia. Musisz podać dokładnie jedną z tych właściwości: file lub code.

UserScriptFilter

Właściwości

  • ids

    string[] opcjonalne

    getScripts zwraca tylko skrypty o identyfikatorach podanych na tej liście.

UserScriptInjection

Chrome 135 i nowsze

Właściwości

  • injectImmediately

    wartość logiczna opcjonalna

    Określa, czy wstrzyknięcie powinno zostać uruchomione w docelowym obiekcie jak najszybciej. Nie jest to jednak gwarancja, że wstrzyknięcie nastąpi przed załadowaniem strony, ponieważ strona może zostać załadowana przed osiągnięciem przez skrypt celu.

  • Lista obiektów ScriptSource definiujących źródła skryptów, które mają zostać wstrzyknięte do celu.

  • Szczegóły określające docel, do którego ma zostać wstrzyknięty skrypt.

  • świat

    ExecutionWorld opcjonalny

    Środowisko JavaScript, w którym ma być wykonywany skrypt. Wartość domyślna to USER_SCRIPT.

  • worldId

    string opcjonalny

    Określa identyfikator świata skryptu użytkownika, w którym ma być wykonywany. Jeśli go pominiesz, skrypt zostanie wykonany w domyślnym świecie skryptu użytkownika. Obowiązuje tylko wtedy, gdy world jest pominięty lub ma wartość USER_SCRIPT. Wartości z początkowym podkreśleniem (_) są zarezerwowane.

WorldProperties

Właściwości

  • csp

    string opcjonalny

    Określa csp na całym świecie. Wartość domyślna to `ISOLATED` csp na całym świecie.

  • SMS

    wartość logiczna opcjonalna

    Określa, czy interfejsy API wiadomości są dostępne. Wartość domyślna to false.

  • worldId

    string opcjonalny

    Chrome 133 lub nowszy

    Określa identyfikator konkretnego świata skryptu użytkownika, który ma zostać zaktualizowany. Jeśli nie zostanie podany, właściwości zostaną zaktualizowane w domyślnym świecie skryptu użytkownika. Wartości z początkowym podkreśleniem (_) są zarezerwowane.

Metody

configureWorld()

Obietnice 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Konfiguruje środowisko wykonawcze `USER_SCRIPT`.

Parametry

  • usługi

    WorldProperties

    Zawiera konfigurację świata skryptu użytkownika.

  • callback

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

execute()

Obietnice Chrome 135+ 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

Wstrzykuje skrypt do kontekstu docelowego. Domyślnie skrypt będzie uruchamiany w czasie document_idle lub natychmiast, jeśli strona została już załadowana. Jeśli właściwość injectImmediately jest ustawiona, skrypt zostanie wstrzyknięty bez oczekiwania, nawet jeśli wczytywanie strony nie zostało jeszcze ukończone. Jeśli skrypt zwraca obietnicę, przeglądarka czeka, aż obietnica zostanie zrealizowana, i zwraca zwróconą wartość.

Parametry

Zwroty

  • Promise<InjectionResult[]>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

getScripts()

Obietnice 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Zwraca wszystkie skrypty użytkownika zarejestrowane dynamicznie w przypadku tego rozszerzenia.

Parametry

Zwroty

  • Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

getWorldConfigurations()

Obietnice Chrome 133 lub nowszy 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Pobiera wszystkie zarejestrowane konfiguracje świata.

Parametry

Zwroty

  • Promise<WorldProperties[]>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

register()

Obietnice 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Rejestruje co najmniej 1 skrypt użytkownika dla tego rozszerzenia.

Parametry

  • Zawiera listę skryptów użytkownika do zarejestrowania.

  • callback

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

resetWorldConfiguration()

Obietnice Chrome 133 lub nowszy 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Resetuje konfigurację świata skryptu użytkownika. Wszystkie skrypty, które wstrzykują do świata określony identyfikator, będą używać domyślnej konfiguracji świata.

Parametry

  • worldId

    string opcjonalny

    Identyfikator świata skryptu użytkownika, który ma zostać zresetowany. W przypadku pominięcia spowoduje zresetowanie domyślnej konfiguracji świata.

  • callback

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

unregister()

Obietnice 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Rejestrowanie wszystkich dynamicznie zarejestrowanych skryptów użytkownika dla tego rozszerzenia zostanie anulowane.

Parametry

  • filtr

    UserScriptFilter opcjonalny

    Jeśli jest określona, ta metoda wyrejestruje tylko skrypty użytkownika, które się z nią zgadzają.

  • callback

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

update()

Obietnice 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Zaktualizuje co najmniej 1 skrypt użytkownika dla tej wtyczki.

Parametry

  • Zawiera listę skryptów użytkownika, które mają zostać zaktualizowane. Właściwość jest aktualizowana tylko w przypadku istniejącego skryptu, jeśli jest ona określona w tym obiekcie. Jeśli podczas analizowania skryptu lub sprawdzania pliku wystąpią błędy albo podane identyfikatory nie będą odpowiadać w pełni zarejestrowanemu skryptowi, żadne skrypty nie zostaną zaktualizowane.

  • callback

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.